*/* $Header: task_pub.hs,v 2.2 01/10/02 10:30:44 przybyls Exp $ */
  nolist
  BEGIN_Ifile  TASK

* task_pub.hs ... an include file
* ===============================

************************************************************************
*                                                                      *
*                  Copyright Hewlett-Packard Co. 1991                  *
*                                                                      *
************************************************************************

************************************************************************
*                                                                      *
*   Module TASK -- Users Manual:  (as68k)                              *
*   ----------------------------                                       *
*   This file defines the assembly-language interface to module TASK,  *
*   the OS multi-tasking CPU scheduler, (implemented in file mem.s).   *
*                                                                      *
*   NOTE:  Only those objects, (macros, constants, etc), whose names   *
*   begin with the module-prefix "TASK_" (all uppercase) are intended  *
*   for PUBLIC use;  any other objects declared in this file must be   *
*   considered PRIVATE ... and subject to change without notice.       *
*                                                                      *
*     TASK_Init  D0,A0,D1,A1                                           *
*     ----------------------                                           *
*       TASK_Init initializes the multi-tasking system, creates and    *
*       starts a user-specified ROOT_Task, transfers control to the    *
*       ROOT_Task ...and NEVER RETURNS!  The ROOT_Task is specified    *
*       in the same way as any other task, and thus TASK_Init takes    *
*       the same calling parameters as TASK_Create.  (In the event     *
*       a TASK_Init failure, a NULL pointer is returned in A0.L.)      *
*                                                                      *
*     TASK_Create  D0,A0,D1,A1                                         *
*     ------------------------                                         *
*       TASK_Create returns the Task_ID (A0.L) of the newly created    *
*       task, or Task_ID=0 if the operation fails (possibly due to     *
*       lack of memory or invalid parameters).  Memory is allocated    *
*       for the task's stack and static variables, the static area     *
*       is initialized (all 0's), and the (optional) task parameter    *
*       block is copied onto the task stack.  Once created, the new    *
*       task waits for a signal from TASK_Start before executing.      *
*                                                                      *
*           D0.L = Task name, 4 chars -- printing ASCII recommended.   *
*                                                                      *
*           A0.L = Pointer to a TASK_Descriptor record containing:     *
*                - ($0,A0).L =  Task execution address                 *
*                - ($4,A0).L =  Task static space (in bytes)           *
*                - ($8,A0).L =  Task stack size (in bytes)             *
*                - ($C,A0).W =  Task priority (0..TASK_IDLE_PRI)       *
*                - ($E,A0).W =  Task time slice (in TASK_Tick ticks)   *
*                                                                      *
*           D1.L = Size of task parameter block (in bytes).            *
*                                                                      *
*           A1.L = Pointer to task parameter block (or NULL).          *
*                                                                      *
************************************************************************

  ??PAGE
* task_pub.hs ... an include file
* ===============================

************************************************************************
*                                                                      *
*     TASK_Start  A0                                                   *
*     --------------                                                   *
*       Signal a newly created task (A0.L) to begin execution.  The    *
*       new task "begins life" with a task parameter block (defined    *
*       by its creator) stacked to mimic the calling arguments of an   *
*       AxLS 'C' function;  the "return address" at the top of stack   *
*       points to an operating system task-exit routine.  Register     *
*       A5 points to the (zero-filled) static variable area;  A6 is    *
*       initialized such that an "UNLK  A6" instruction will "dump"    *
*       the task parameter block and provide additional stack space.   *
*                                                                      *
*     TASK_Send_Sig  D0,A0                                             *
*     --------------------                                             *
*       Send the signal(s) indicated by the signal-mask (D0.W) to      *
*       the target task (A0.L);  if the task currently WAITING for     *
*       ANY of these signals, restore the task to the READY state.     *
*                                                                      *
*     TASK_Wait_Sig  D0                                                *
*     -----------------                                                *
*       Check the specified signals (D0.W) of the calling task;  if    *
*       ANY requested signal has been asserted, return immediately;    *
*       otherwise, WAIT (suspend execution) until one (or more) of     *
*       the requested signals is posted.  In either case, return a     *
*       mask (D0.W) indicating (REQUESTED .AND. AVAILABLE) signals.    *
*       Signal bits associated with the lower byte of the mask are     *
*       "volatile", i.e., they are cleared automatically when read;    *
*       the upper-byte signals are "sticky", they are cleared only     *
*       in response to an explicit TASK_Clr_Sig request.               *
*                                                                      *
*     TASK_Get_Sig  D0                                                 *
*     ----------------                                                 *
*       Similar to TASK_Wait_Sig except that the caller never blocks   *
*       waiting for a signal;  if no requested signal is available,    *
*       a "no match" indication (D0.W=0) is returned immediatey.       *
*                                                                      *
*     TASK_Clr_Sig  D0                                                 *
*     -----------------                                                *
*       Clear the specified signals (D0.W) of the calling task.        *
*                                                                      *
*     TASK_Get_SigT  A0,D0                                             *
*     --------------------                                             *
*       Special OS entry point to TASK_Get_Sig -- allows signals to    *
*       be received by an ISR or another task;  A0 is the Task_ID of   *
*       the task whose signals are to be "read".  (Restricted use!)    *
*                                                                      *
*     TASK_Clr_SigT  D0,A0                                             *
*     --------------------                                             *
*       Special OS entry point to TASK_Clr_Sig -- allows signals to    *
*       be cleared by an ISR or another task;  A0 is the Task_ID of    *
*       the task whose signals are to be cleared.  (Restricted use!)   *
*                                                                      *
************************************************************************

  ??PAGE
* task_pub.hs ... an include file
* ===============================

************************************************************************
*                                                                      *
*     TASK_Current  <expr>                                             *
*     --------------------                                             *
*       Returns the Task_ID of the currently executing task.  The ID   *
*       is returned directly to the destination specified by <expr>;   *
*       <expr> may specify any location which is a valid operand for   *
*       instruction  "MOVE.L  mem,<expr>".                             *
*                                                                      *
*     TASK_Find_ID  D0,A0                                              *
*     -------------------                                              *
*       Returns the Task_ID (A0) of the task having the specified      *
*       four-character symbolic name (D0.L).                           *
*                                                                      *
*     TASK_Get_Name  A0,D0                                             *
*     --------------------                                             *
*       Returns the symbolic name (D0.L) if the specified task (A0).   *
*                                                                      *
*     TASK_Get_MyName  D0                                              *
*     -------------------                                              *
*       Returns the symbolic name (D0.L) of the executing task.        *
*                                                                      *
*     TASK_Get_Pri  A0,D0                                              *
*     -------------------                                              *
*       Returns the task priority (D0.W) of the specified task (A0).   *
*                                                                      *
*     TASK_Get_MyPri  D0                                               *
*     ------------------                                               *
*       Returns the task priority (D0.W) of the executing task.        *
*                                                                      *
*     TASK_Set_Pri  D0,A0                                              *
*     -------------------                                              *
*       Sets the priority (D0.W) of the specified task (A0).           *
*                                                                      *
*     TASK_Set_MyPri  D0                                               *
*     ------------------                                               *
*       Sets the priority (D0.W) of the executing task.                *
*                                                                      *
*     TASK_Yield                                                       *
*     ----------                                                       *
*       The calling task yields control of the CPU and is rescheduled  *
*       behind all other READY tasks of the same priority.  If there   *
*       are no other READY tasks at the caller's priority, TASK_Yield  *
*       has no effect -- except to "refill" the caller's time-slice.   *
*       NOTE: Yield must NOT be called by interrupt service routines.  *
*                                                                      *
************************************************************************

  ??PAGE
* task_pub.hs ... an include file
* ===============================

************************************************************************
*                                                                      *
*     TASK_Get_Slc  A0,D0                                              *
*     -------------------                                              *
*       Returns the time-slice (D0.W) of the specified task (A0).      *
*                                                                      *
*     TASK_Get_MySlc  D0                                               *
*     ------------------                                               *
*       Returns the time-slice (D0.W) of the executing task.           *
*                                                                      *
*     TASK_Set_Slc  D0,A0                                              *
*     -------------------                                              *
*       Sets the time-slice (D0.W) of the specified task (A0).         *
*                                                                      *
*     TASK_Set_MySlc  D0                                               *
*     ------------------                                               *
*       Sets the time-slice (D0.W) of the executing task.              *
*                                                                      *
*     TASK_Tick                                                        *
*     ---------                                                        *
*       TASK_Tick is called by the periodic time interrupt to drive    *
*       the operating system's round-robin time-slicing service. It    *
*       also interacts with the IDLE_Task to monitor CPU loading.      *
*                                                                      *
*     TASK_Int_Entry                                                   *
*     --------------                                                   *
*       TASK_Int_Entry is used to notify the task manager that an      *
*       interrupt service routine (ISR) is in progress.  It must be    *
*       called (by the interrupt manager) at the beginning of any      *
*       ISR which might (directly or indirectly) use the services      *
*       of the task manager.                                           *
*                                                                      *
*     TASK_Int_Exit                                                    *
*     -------------                                                    *
*       TASK_Int_Exit is used to notify the task manager that _ALL_    *
*       ISR activity is about to terminate.  If must be called just    *
*       before exiting the outermost level of nested interrupts.       *
*                                                                      *
************************************************************************

  ??PAGE
* task_pub.hs ... an include file
* ===============================


* Variables:
* ----------
                EXTERNAL        SysData:Task_Current
                EXTERNAL        SysData:Task_InISR

* Procedures:
* -----------
                EXTERNAL        SysCode:Task_init
                EXTERNAL        SysCode:Task_create
                EXTERNAL        SysCode:Task_start

                EXTERNAL        SysCode:Task_send_sig
                EXTERNAL        SysCode:Task_wait_sig
                EXTERNAL        SysCode:Task_get_sig
                EXTERNAL        SysCode:Task_clr_sig
                EXTERNAL        SysCode:Task_get_sigt
                EXTERNAL        SysCode:Task_clr_sigt

                EXTERNAL        SysCode:Task_find_id
                EXTERNAL        SysCode:Task_get_name
                EXTERNAL        SysCode:Task_get_myname

                EXTERNAL        SysCode:Task_set_pri
                EXTERNAL        SysCode:Task_set_mypri
                EXTERNAL        SysCode:Task_get_pri
                EXTERNAL        SysCode:Task_get_mypri
                EXTERNAL        SysCode:Task_yield

                EXTERNAL        SysCode:Task_set_slc
                EXTERNAL        SysCode:Task_set_myslc
                EXTERNAL        SysCode:Task_get_slc
                EXTERNAL        SysCode:Task_get_myslc

                EXTERNAL        SysCode:Task_tick
                EXTERNAL        SysCode:Task_dispatch   ;TASK_Int_Exit


  ??PAGE
* task_pub.hs ... an include file
* ===============================



TASK_Init       MACRO           name,spec,np,pp
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_np       <\3>,d1,D1      ;3rd param must be D1,
                ??FAIL_np       <\4>,a1,A1      ;4th param must be A1,
                ??FAIL_p        <\5\6\7\8>      ;No other parameters.
                  jsr           Task_init       ;Normally, NO RETURN!
                ENDM



TASK_Create     MACRO           name,spec,np,pp
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_np       <\3>,d1,D1      ;3rd param must be D1,
                ??FAIL_np       <\4>,a1,A1      ;4th param must be A1,
                ??FAIL_p        <\5\6\7\8>      ;No other parameters.
                  jsr           Task_create
                ENDM



TASK_Start      MACRO           task
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,a0,A0      ;1st param must be A0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_start
                ENDM


  ??PAGE
* task_pub.hs ... an include file
* ===============================



TASK_Send_Sig   MACRO           sigs,task
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_send_sig
                ENDM



TASK_Wait_Sig   MACRO           sigs
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_wait_sig
                ENDM



TASK_Get_Sig    MACRO           sigs
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_get_sig
                ENDM



TASK_Clr_Sig    MACRO           sigs
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_clr_sig
                ENDM



TASK_Get_SigT   MACRO           task,mask
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,a0,A0      ;1st param must be A0,
                ??FAIL_np       <\2>,d0,D0      ;2nd param must be D0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_get_sigt
                ENDM



TASK_Clr_SigT   MACRO           sigs,task
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_clr_sigt
                ENDM


  ??PAGE
* task_pub.hs ... an include file
* ===============================



TASK_Current    MACRO           dst_ea
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,<*>        ;1st param must exist,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  move.l        Task_Current,\1
                ENDM



TASK_Find_ID    MACRO           name,task
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_find_id
                ENDM



TASK_Get_Name   MACRO           task,name
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,a0,A0      ;1st param must be A0,
                ??FAIL_np       <\2>,d0,D0      ;2nd param must be D0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_get_name
                ENDM



TASK_Get_MyName MACRO           name
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_get_myname
                ENDM


  ??PAGE
* task_pub.hs ... an include file
* ===============================


TASK_Get_Pri    MACRO           task,pri
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,a0,A0      ;1st param must be A0,
                ??FAIL_np       <\2>,d0,D0      ;2nd param must be D0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_get_pri
                ENDM



TASK_Get_MyPri  MACRO           pri
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_get_mypri
                ENDM



TASK_Set_Pri    MACRO           pri,task
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_set_pri
                ENDM



TASK_Set_MyPri  MACRO           pri
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_set_mypri
                ENDM



TASK_Yield      MACRO
                ??FAIL_p        <\0\1\2\3>      ;No params allowed.
                  jsr           Task_yield
                ENDM


  ??PAGE
* task_pub.hs ... an include file
* ===============================



TASK_Get_Slc    MACRO           task,slice
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,a0,A0      ;1st param must be A0,
                ??FAIL_np       <\2>,d0,D0      ;2nd param must be D0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_get_slc
                ENDM



TASK_Get_MySlc  MACRO           slice
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_get_myslc
                ENDM




TASK_Set_Slc    MACRO           slice,task
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_np       <\2>,a0,A0      ;2nd param must be A0,
                ??FAIL_p        <\3\4\5\6>      ;No other parameters.
                  jsr           Task_set_slc
                ENDM



TASK_Set_MySlc  MACRO           slice
                ??FAIL_p        <\0>            ;No qualifier allowed,
                ??FAIL_np       <\1>,d0,D0      ;1st param must be D0,
                ??FAIL_p        <\2\3\4\5>      ;No other parameters.
                  jsr           Task_set_myslc
                ENDM


  ??PAGE
* task_pub.hs ... an include file
* ===============================



TASK_Tick       MACRO
                ??FAIL_p        <\0\1\2\3>      ;No params allowed.
                  jsr           Task_tick
                ENDM



TASK_Int_Entry  MACRO
                ??FAIL_p        <\0\1\2\3>      ;No params allowed.
                  bset.b        #7,Task_InISR   ;Detect ASR.W's       20
                ENDM



TASK_Int_Exit   MACRO
                ??FAIL_p        <\0\1\2\3>      ;No params allowed.
                  asl.w         Task_InISR      ;If b14..b0 = 0, no   16
                  beq.s         ti_x\@          ;swap pend'g, quit;   10
                  clr.w         Task_InISR      ;else clear pending   16
                  jsr           Task_dispatch   ;flag and task-swap.  ??
ti_x\@            equ           *               ;If swap t=??? else t=26
                ENDM



                list

* End of include file task_pub.hs
  END_Ifile     TASK
